react-native-vector-icons

What is react-native-vector-icons?

The react-native-vector-icons package provides a set of customizable icons for React Native applications. It includes a variety of icon sets and allows for easy integration and customization of icons in your app.

What are react-native-vector-icons's main functionalities?

Basic Icon Usage

This feature allows you to use icons from various icon sets like FontAwesome. You can specify the icon name, size, and color.

import Icon from 'react-native-vector-icons/FontAwesome';

const MyComponent = () => (
  <Icon name="rocket" size={30} color="#900" />
);

Icon Button

You can use icons as buttons by wrapping them in a TouchableOpacity component. This makes the icon interactive.

import Icon from 'react-native-vector-icons/FontAwesome';
import { TouchableOpacity } from 'react-native';

const MyComponent = () => (
  <TouchableOpacity>
    <Icon name="rocket" size={30} color="#900" />
  </TouchableOpacity>
);

Custom Icon Fonts

This feature allows you to create custom icon sets from Fontello or other similar services. You can then use these custom icons in your app.

import { createIconSetFromFontello } from 'react-native-vector-icons';
import fontelloConfig from './config.json';

const Icon = createIconSetFromFontello(fontelloConfig);

const MyComponent = () => (
  <Icon name="custom-icon" size={30} color="#900" />
);

Other packages similar to react-native-vector-icons

react-native-elements

react-native-elements is a UI toolkit for React Native that includes a set of customizable components, including icons. It uses react-native-vector-icons under the hood but provides a more comprehensive set of UI components.

react-native-paper

react-native-paper is a library that provides Material Design components for React Native. It includes an IconButton component that allows you to use icons from various icon sets, similar to react-native-vector-icons.

README

Perfect for buttons, logos and nav/tab bars. Easy to extend, style and integrate into your project.

Main advantages over react-native-icons

• You can use your own custom icon sets. Supports SVG via Fontello or regular icon fonts.
• You can use native TabBarIOS.
• You can use icons inline with Text components as emojis or to create buttons.
• You can use the icon as an image if a native component requires it (such as NavigatorIOS).
• Most common use cases is JavaScript only and thus enables wider possibilities of styling (and is easier to integrate with your project).
• No need to define width and height styles.
• Presentational stuff like size and color can be defined in your stylesheet instead of via a property (if you want to).
• Icons scale with accessibility settings (unless disabled).

Pst! Migrating from react-native-icons? Scroll down for more information.

Bundled Icon Sets

• Entypo by Daniel Bruce (411 icons)
• EvilIcons by Alexander Madyankin & Roman Shamin (v1.8.0, 70 icons)
• FontAwesome by Dave Gandy (v4.6.3, 634 icons)
• Foundation by ZURB, Inc. (v3.0, 283 icons)
• Ionicons by Ben Sperry (v3.0.0, 859 icons)
• MaterialIcons by Google, Inc. (v2.2.3, 932 icons)
• Octicons by Github, Inc. (v3.5.0, 166 icons)
• Zocial by Sam Collins (v1.0, 100 icons)

Installation

$ npm install react-native-vector-icons --save

iOS

Option: Manually

If you want to use any of the bundled icons, you need to add the icon fonts to your Xcode project. Just follow these steps:

• Browse to node_modules/react-native-vector-icons and drag the folder Fonts (or just the ones you want) to your project in Xcode. Make sure your app is checked under "Add to targets" and that "Create groups" is checked if you add the whole folder.
• Edit Info.plist and add a property called Fonts provided by application (or UIAppFonts if Xcode won't autocomplete/not using Xcode) and type in the files you just added. It will look something like this:

Note: you need to recompile your project after adding new fonts, also ensure that they also appear under Copy Bundle Resources in Build Phases.

If you want to use the TabBar/NavigatorIOS integration or use getImageSource, then you need to add RNVectorIcons.xcodeproj to Libraries and add libRNVectorIcons.a to Link Binary With Libraries under Build Phases. More info and screenshots about how to do this is available in the React Native documentation.

Option: With CocoaPods

Add the following to your Podfile and run pod update:

pod 'RNVectorIcons', :path => 'node_modules/react-native-vector-icons'

Edit Info.plist as described above.

Option: With rnpm

$ rnpm link

Note: Some users are having trouble using this method, try one of the others if you are too.

Android

Option: With Gradle (recommended)

This method has the advantage of fonts being copied from this module at build time so that the fonts and JS are always in sync, making upgrades painless.

Edit android/app/build.gradle ( NOT android/build.gradle ) and add the following:

apply from: "../../node_modules/react-native-vector-icons/fonts.gradle"

To customize the files being copied, add the following instead:

project.ext.vectoricons = [
    iconFontNames: [ 'MaterialIcons.ttf', 'EvilIcons.ttf' ] // Name of the font files you want to copy
]

apply from: "../../node_modules/react-native-vector-icons/fonts.gradle"

Option: Manually

• Copy the contents in the Fonts folder to android/app/src/main/assets/fonts (note lowercase font folder).

Integrating library for getImageSource and ToolbarAndroid support

These steps are optional and only needed if you want to use the Icon.getImageSource function or using custom icons in the Icon.ToolbarAndroid component.

• Edit android/settings.gradle to look like this (without the +):

  rootProject.name = 'MyApp'
  
  include ':app'
  
  + include ':react-native-vector-icons'
  + project(':react-native-vector-icons').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-vector-icons/android')
  

• Edit android/app/build.gradle (note: app folder) to look like this:

  apply plugin: 'com.android.application'
  
  android {
    ...
  }
  
  dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
    compile "com.android.support:appcompat-v7:23.0.1"
    compile "com.facebook.react:react-native:+"  // From node_modules
  + compile project(':react-native-vector-icons')
  }
  

• Edit your MainApplication.java (deep in android/app/src/main/java/...) to look like this (note two places to edit):

  package com.myapp;
  
  + import com.oblador.vectoricons.VectorIconsPackage;
  
  ....
  
    @Override
    protected List<ReactPackage> getPackages() {
      return Arrays.<ReactPackage>asList(
        new MainReactPackage()
  +   , new VectorIconsPackage()
      );
    }
  
  }
  

Note: If you're using React Native (Android) <= 0.17, follow this instructions

Option: With rnpm

$ rnpm link

Note: Some users are having trouble using this method, try one of the others if you are too.

OSX via react-native-desktop

• Browse to node_modules/react-native-vector-icons and drag the folder Fonts to your project in Xcode. Make sure your app is checked under "Add to targets" and that "Create folder references" is checked.
• Edit Info.plist and add a property called Application fonts resource path (or ATSApplicationFontsPath if Xcode won't autocomplete/not using Xcode) and type Fonts as the value.

Note: you need to recompile your project after adding new fonts, also ensure that the Fonts folder also appear under Copy Bundle Resources in Build Phases.

Icon Component

You can either use one of the bundled icons above or roll your own custom font.

import Icon from 'react-native-vector-icons/FontAwesome';
const myIcon = (<Icon name="rocket" size={30} color="#900" />)

Properties

Any Text property and the following:

Prop	Description	Default
size	Size of the icon, can also be passed as fontSize in the style object.	12
name	What icon to show, see Icon Explorer app or one of the links above.	None
color	Color of the icon.	Inherited

Styling

Since Icon builds on top of the Text component, most style properties will work as expected, you might find it useful to play around with these:

• backgroundColor
• borderWidth
• borderColor
• borderRadius
• padding
• margin
• color
• fontSize

NOTE: On android Text doesn't currently support border* styles, to circumvent this simply wrap your Icon with a View.

By combining some of these you can create for example :

Icon.Button Component

A convenience component for creating buttons with an icon on the left side.

import Icon from 'react-native-vector-icons/FontAwesome';
const myButton = (
  <Icon.Button name="facebook" backgroundColor="#3b5998" onPress={this.loginWithFacebook}>
    Login with Facebook
  </Icon.Button>
);

const customTextButton = (
  <Icon.Button name="facebook" backgroundColor="#3b5998">
    <Text style={{fontFamily: 'Arial', fontSize: 15}}>Login with Facebook</Text>
  </Icon.Button>
);

Properties

Any Text, TouchableHighlight or TouchableWithoutFeedback property in addition to these:

Prop	Description	Default
color	Text and icon color, use iconStyle or nest a Text component if you need different colors.	white
size	Icon size.	20
iconStyle	Styles applied to the icon only, good for setting margins or a different color.	{marginRight: 10}
backgroundColor	Background color of the button.	#007AFF
borderRadius	Border radius of the button, set to 0 to disable.	5
onPress	A function called when the button is pressed.	None

Usage as PNG image/source object

Convenient way to plug this in into other components that rely on bitmap images rather than scalable vector icons. Takes the arguments name, size and color as described above.

Icon.getImageSource('user', 20, 'red').then((source) => this.setState({ userIcon: source }));

For a complete example check out the TabBarExample project.

Usage with TabBarIOS

Simply use Icon.TabBarItemIOS instead of TabBarIOS.Item. This is an extended component that works exactly the same but with three additional properties:

Prop	Description	Default
iconName	Name of the default icon (similar to TabBarIOS.Item icon)	None
selectedIconName	Name of the selected icon (similar to TabBarIOS.Item selectedIcon).	iconName
iconSize	Size of the icon.	30
iconColor	Color of the icon.	None
selectedIconColor	Color of the selected icon.	iconColor

For example usage see Examples/TabBarExample or the examples section below. Don't forget to import and link to this project as described above if you are going to use the TabBar integration.

Note: using iconColor and selectedIconColor requires the attribute renderAsOriginal to be set to true on Icon.TabBarItemIOS.

Usage with NavigatorIOS

Use Icon.getImageSource to get an image source object and pass it as you would with backButtonIcon, leftButtonIcon or rightButtonIcon.

Note: Since NavigatorIOS doesn't rerender with new state and the async nature of getImageSource you must not use it with initialRoute until the icon is rendered, but any view added by push should be fine. Easiest way is to simple add an if statment at the beginning of you render method like this:

  render() {
    if (!this.state.myIcon) {
      return false;
    }
    return (<NavigatorIOS ... />);
  }

Facebook writes:

Development belongs to open-source community - not used by the React Native team on their apps. A result of this is that there is currently a backlog of unresolved bugs, nobody who uses this has stepped up to take ownership for it yet.

You are probably better off with Navigator.NavigationBar or react-native-navbar.

Usage with ToolbarAndroid

Simply use Icon.ToolbarAndroid instead of React.ToolbarAndroid, this is composition of the underlying ToolbarAndroid component that works the same but any *icon property also takes *iconName:

Prop	Description	Default
navIconName	Name of the navigation icon (similar to ToolbarAndroid navIcon)	None
overflowIconName	Name of the overflow icon (similar to ToolbarAndroid overflowIcon).	none
actions	Possible actions on the toolbar as part of the action menu, takes the additional arguments iconName, iconColor and iconSize.	none
iconSize	Size of the icons.	24
iconColor	Color of the icons.	black

For example usage see Examples/IconExplorer/index.android.jsor the examples section below. Don't forget to import and link to this project as described above if you are going to use the ToolbarAndroid integration.

Custom Fonts

createIconSet(glyphMap, fontFamily[, fontFile])

Returns your own custom font based on the glyphMap where the key is the icon name and the value is either a UTF-8 character or it's character code. fontFamily is the name of the font NOT the filename. Open the font in Font Book.app or similar to learn the name. Optionally pass the third fontFile argument for android support, it should be a path to the font file in you asset folder.

import { createIconSet } from 'react-native-vector-icons';
const glyphMap = { 'icon-name': 1234, test: '∆' };
const Icon = createIconSet(glyphMap, 'FontName');

createIconSetFromFontello(config[, fontFamily[, fontFile]])

Convenience method to create a custom font based on a fontello config file. Don't forget to import the font as described above and drop the config.json somewhere convenient in your project.

import { createIconSetFromFontello } from 'react-native-vector-icons';
import fontelloConfig from './config.json';
const Icon = createIconSetFromFontello(fontelloConfig);

createIconSetFromIcoMoon(config[, fontFamily[, fontFile]])

import { createIconSetFromIcoMoon } from 'react-native-vector-icons';
import icoMoonConfig from './config.json';
const Icon = createIconSetFromIcoMoon(icoMoonConfig);

Make sure you're using the Download option in IcoMoon, and use the .json file that's included in the .zip you've downloaded. You'll also need to import the .ttf font file into your project, following the instructions above.

Animation

React Native comes with an amazing animation library called Animated. To use it with an icon, simply create an animated component with this line: const AnimatedIcon = Animated.createAnimatedComponent(Icon). You can also use the higher level animation library react-native-animatable.

Examples

IconExplorer

Try the IconExplorer project in Examples/IconExplorer folder, there you can also search for any icon.

Basic Example

import Icon from 'react-native-vector-icons/Ionicons';

function ExampleView(props) {
  return (<Icon name="ios-person" size={30} color="#4F8EF7" />);
}

TabBarIOS

Full example in TabBarExample project in Examples/TabBarExample folder.

import { View, Text, TabBarIOS } from 'react-native';
import Icon from 'react-native-vector-icons/Ionicons';

function TabBarView(props) {
  return (
    <TabBarIOS>
      <Icon.TabBarItem
        title="Home"
        iconName="ios-home-outline"
        selectedIconName="ios-home"
        >
        <View style={styles.tabContent}><Text>Home Tab</Text></View>
      </Icon.TabBarItem>
    </TabBarIOS>
  );
}

ToolbarAndroid

import Icon from 'react-native-vector-icons/Ionicons';

function ToolbarView(props) {
  return (
    <Icon.ToolbarAndroid
      title="Home"
      titleColor="white"
      navIconName="md-arrow-back"
      onIconClicked={props.navigator.pop}
      actions={[
        { title: 'Settings', iconName: 'md-settings', iconSize: 30, show: 'always' },
        { title: 'Follow me on Twitter', iconName: 'logo-twitter', iconColor: "#4099FF", show: 'ifRoom' },
      ]}
      overflowIconName="md-more"
    />
  );
}

Inline Icons

import { Text } from 'react-native';
import Icon from 'react-native-vector-icons/Ionicons';

function ExampleView(props) {
  return (<Text>Lorem <Icon name="ios-book" color="#4F8EF7" /> Ipsum</Text>);
}

Community examples

• react-native-dribbble-app
• voximplant react-native-demo
• product-kitty (blog post)

Generating your own icon set from a CSS file

If you already have a icon font with associated CSS file then you can easily generate a icon set with the generate-icon script.

Example usage:

./node_modules/.bin/generate-icon path/to/styles.css --componentName=MyIcon --fontFamily=myicon > Components/MyIcon.js

Options

Any flags not listed below, like --componentName and --fontFamily, will be passed on to the template.

-p, --prefix

CSS selector prefix [default: ".icon-"]

-t, --template

Template in lodash format [default: "./template/iconSet.tpl"]

For default template please provide --componentName and --fontFamily.

-o, --output

Save output to file, defaults to STDOUT

Changelog

Migrating from react-native-icons

NOTE: This approach is unsupported and new apps / views should NOT use this component.

With react-native-icons recently being discontinued, users switching to this library might not want to rewrite all their code. For that use case I've written a drop in replacement component that uses the same icon name syntax. It might break some layouts since the underlying component is different. To use this, simply replace your react-native-icons import statement with this:

import Icon from 'react-native-vector-icons/RNIMigration';

Troubleshooting

The icons show up as a crossed out box on Android

• Make sure you've copied the font to android/app/src/main/assets/fonts.
• Delete the android/app/build folder.
• Recompile the project.

Red screen with "Unrecognized font family" error on iOS

• Make sure you've added the fonts to your XCode project.
• Check that the font you are trying to use appears in Info.plist, if you've added the whole folder and it's blue in color, then you need to add it to the path.
• Check that the font is copied in the Copy Bundle Resources in Build Phases.
• Recompile the project.

Android build fails on Windows for no good reason

Both npm and android file hierarchies tend to get very deep and even worse when you combine them. Since Windows file system has a max length, long file name addresses will result in numerous errors including Execution failed for task ':react-native-vector-icons:processReleaseResources'. So try to keep the path to your project folder as short as possible.

License

This project is licenced under the MIT License.

Any bundled fonts are copyright to their respective authors and mostly under MIT or SIL OFL.